home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-11 / pdrd2.zip / RD.ZIP / API.RD next >
Text File  |  1993-01-11  |  8KB  |  202 lines
  1. /*
  2.         API.RD
  3. */
  4.  
  5.  
  6. ADr_version() --> <nVersionNumber>
  7. ----------------------------------
  8. Returns version number.
  9.  
  10.  
  11. ADr_abort( <nEngine>, [nExitCode] ) --> nil
  12. -------------------------------------------
  13. Aborts the Read.  If [nExitCode] is passed, it posts it as the Read exit
  14. code.  Otherwise, it posts the default RX_ABORT.
  15.  
  16.  
  17. ADr_save( <nEngine>, [nExitCode] ) --> nil
  18. ------------------------------------------
  19. Attempts to save the current Get, then exits the Read.  If [nExitCode]
  20. is passed, it posts it as the Read exit code.  Otherwise, it posts the
  21. default RX_SAVE.
  22.  
  23. NOTE that if the current value of the current Get is invalid,  ADr_save()
  24. will not proceed.
  25.  
  26.  
  27. ADr_popup( <nEngine>, <aOptions>, [nRow], [nCol], [aTrigger],;
  28.         [lForce] ) --> <nSel>
  29. -------------------------------------------------------------
  30. Pops up a picklist of options for a character Get.  Returns a the index
  31. position of the seleccted option, or zero if the picklist was aborted.
  32. Also, if a selection was made, the current Get is automatically updated
  33. with it.  When using it as a validation function make sure the return value
  34. of the Valid clause is a logical value.
  35.  
  36.    VALID {|e| ADr_popup( e, aOptions )}            // wrong usage
  37.    VALID {|e| ADr_popup( e, aOptions ) > 0}        // correct usage
  38.  
  39. [nRow] and [nCol] are the top/left coordinates of the popup box.  They
  40. default to the top/left corner of the screen.
  41.  
  42. [aTrigger] is an aptional array of the index positions of the trigger
  43. keys.  Defaults to an array of 1s (the numeric One).
  44.  
  45. [lForce] is an optional logical value.  If it is FALSE, the picklist is
  46. not popped up unless the current entry is invalid.  Defaults to FALSE.
  47.  
  48. The popup is based on the mouseable ADvermenu().
  49.  
  50.  
  51. ADr_required( <nEngine>, [bMessage] ) --> <lFilled>
  52. ---------------------------------------------------
  53. Typically used in Get validation, it returns a TRUE if the current Get is
  54. not empty.  Otherwise, it returns a FALSE and EVALuates [bMessage], passing
  55. to it <nEngine>.  [bMessage] defaults to:
  56.  
  57.    {|e| ADmessage( { "May not be left empty" } )}
  58.  
  59. Note that a Get is "empty" in Clipper-sense, that is:
  60.  
  61.     1.  if type == "C" and the value is "" or all spaces, or
  62.     2.  if type == "N" and the value is 0, or
  63.     3.  if type == "L" and the value is .F., or
  64.     4.  if type == "D" and the value is ctod( "  /  /  " )
  65.  
  66. Obviously, this function may be useful only in "C" and "D" Gets.  But then
  67. again, these are the most common Gets you do not want left blank.
  68.  
  69.  
  70. ADr_filled( <nEngine>, <aFilled>, [bMessage] ) --> <lFilled>
  71. ------------------------------------------------------------
  72. Checks to see if all the Gets whose index positions are included in
  73. <aFilled> are filled.  If at least one is empty,  it returns a FALSE.
  74. Before returning a FALSE, it EVALuates [bMessage] if it is passed, passing
  75. to it <nEngine>.
  76.  
  77.  
  78. ADr_varget( <nEngine>, [nthGet] ) --> <xValue>
  79. ----------------------------------------------
  80. Returns the value of the [nthGet] Get.  If [nthGet] is not passed, or if
  81. an invalid value is passed, it defaults to the current Get.  If [nthGet]
  82. refers to the current Get, the return value is the current contents of the
  83. edit buffer.
  84.  
  85.  
  86. ADr_varput( <nEngine>, <xValue>, [nthGet] ) --> nil
  87. ---------------------------------------------------
  88. Replaces the value of the [nthGet] Get with <xValue>.  If [nthGet] is not
  89. passed, or if an invalid value is passed, it defaults to the current Get.
  90. This function also updates the Get display and sets the o:changed instant
  91. variable to TRUE.
  92.  
  93.  
  94. ADr_jump( <nEngine>, <nthGet>, [lRightAway] ) --> <lPossible>
  95. -------------------------------------------------------------
  96. Instructs the engine to jump to the <nthGet> Get and returns a logical
  97. <lPossible>, which is TRUE if it is possible to jump.  It would be possible
  98. to jump if both these conditions are TRUE:
  99.  
  100.    a.  The <nthGet> Get is focusable in the current context of the Read.
  101.    b.  <nthGet> is a valid value, that is, it is not less than 1 nor
  102.        greater than the number of Gets.
  103.  
  104. If the jump is possible, it will not be carried out if the current entry
  105. in the current Get is invalid.
  106.        
  107. Typically, ADr_jump() is called via a Valid clause.  In this context, the
  108. jump occurs after validation.  In any other context, it is possible to force
  109. the jump to happen right away by passing a TRUE in [lRightAway].  In such
  110. a situation, ADread() first validates the current entry, and proceeds to
  111. jump if it is valid.  Note that if a TRUE [lRightAway] is passed in the
  112. context of Valid clause, the validation routine will be called recursively,
  113. causing a "Processor stack fault error".  The bottom line is: Do not pass a
  114. TRUE [lRightAway] when calling ADr_jump() within a Valid clause.
  115.  
  116.  
  117. ADr_keys( <nEngine>, [aKeys], [bKeysHandler] ) --> nil
  118. ------------------------------------------------------
  119. Defines a set of hot keys and a hot key handler.
  120.  
  121. [aKeys] is an array of the inkey codes of the hot keys to be defined.
  122.  
  123. [bKeysHandler] is a codeblock that is EVALuated when one of the hot keys
  124. is pressed.  Three parameters are passed to the handler:
  125.  
  126.    1 - the numeric engine identifier, <nEngine>
  127.    2 - the index position of the pressed hot key.
  128.    3 - the inkey value of the pressed hot key.
  129.  
  130.  
  131. ADr_lbuttons( <nEngine>, [aSpots], [bLBHandler] ) --> nil
  132. ---------------------------------------------------------
  133. Defines a set of left button hot spots and a hot spot handler.
  134.  
  135. [aSpots] is an array of the coordinates of the hot spots to be defined.
  136.  
  137. [bLBHandler] is a codeblock that is EVALuated when one of the hot spots
  138. is clicked.  Four parameters are passed to the handler:
  139.  
  140.    1 - the numeric engine identifier, <nEngine>
  141.    2 - the index position of the clicked hot key.
  142.    3 - the mouse cursor row position when the left button was clicked.
  143.    4 - the mouse cursor column position when the left button was clicked.
  144.  
  145.  
  146. ADr_rbuttons( <nEngine>, [aSpots], [bRBHandler] ) --> nil
  147. ---------------------------------------------------------
  148. Defines a set of right button hot spots and a hot spot handler.
  149.  
  150. [aSpots] is an array of the coordinates of the hot spots to be defined.
  151.  
  152. [bRBHandler] is a codeblock that is EVALuated when one of the hot spots
  153. is clicked.  Four parameters are passed to the handler:
  154.  
  155.    1 - the numeric engine identifier, <nEngine>
  156.    2 - the index position of the clicked hot key.
  157.    3 - the mouse cursor row position when the right button was clicked.
  158.    4 - the mouse cursor column position when the right button was clicked.
  159.  
  160.  
  161. ADr_blank( <nEngine>, [xGets] ) --> nil
  162. ---------------------------------------
  163. Blanks specific or all Gets.  Which Gets will be blanked will depend on the
  164. value of [xGets]:
  165.  
  166.    1.  If [xGets] == nil: only the current Get
  167.    2.  If [xGets] is a numeric: the referenced Get 
  168.    3.  If [xGets] is an empty array: all the Gets
  169.    4.  If [xGets] is an array of numerics: the Gets pointed to by the
  170.            numeric elements
  171.  
  172.  
  173. ADr_exit( <nEngine>, <bExit> ) --> nil
  174. --------------------------------------
  175. Assigns an Exit Block to the Read engine.  The Exit Block is a codeblock
  176. that is EVALuated just before the Read is exited (NOT aborted).  It must
  177. return a logical value.  If it EVALuates to a TRUE, the Read proceeds to
  178. exit.  The codeblock is automatically passed <nEngine>.  Typically, the
  179. Exit Block is used to validate the whole Read.
  180.  
  181.  
  182. ADr_nthget( <nEngine> ) --> <nNthGet>
  183. -------------------------------------
  184. Returns the index position of the current Get.
  185.  
  186.  
  187. ADr_again( <nEngine> ) --> <nExitCode>
  188. --------------------------------------
  189. Re-activates an exited live Read engine.
  190.  
  191.  
  192. ADr_expattr( <nEngine>, [aCoords], [cColor], [cFrame], [cPrompt ) --> nil
  193. -------------------------------------------------------------------------
  194. Changes the default memoedit box coordinates, color, frame and prompt.  The
  195. coordinates default to {8,20,16,59}; the color to the current color; and
  196. the frame to "╒═╕│╛═╘│ ".
  197.  
  198. NOTE: [cPrompt] may be sued to translate the English default,
  199.       "Esc:Abort    Tab:Save    F1:Help", to any language.  Note that the
  200.       only spaces in the prompt string are the spaces between the options.
  201.       No space must be present within an option.
  202.